Datafiles created with the Prograph Datafile Manager can be accessed by multiple users if opened in Shared mode (see the description for db-open primitive later in this chapter). To make this possible, the datafile must reside on a shared volume within an AppleTalk network.
Applications that open a shared datafile must be aware that other applications may be accessing that datafile. From a programmer窶冱 perspective, the following items must be considered when accessing a datafile:
1. To replace an existing cluster, lock the cluster, call cluster, replace, then unlock the cluster.
2. Attempting to read a cluster may result in an error indicating that someone else has locked the cluster; you may try again later;
3. It is not necessary to explicitly flush a shared datafile, since all shared datafiles are flushed automatically after each write.
Locking and Unlocking Clusters *490*
In a shared datafile, multiple users can read a cluster simultaneously; however, only a single user may safely overwrite a cluster. For this reason it is necessary to lock a cluster before writing to the datafile, to prevent another user from writing to the same cluster at the same time. After an application has overwritten a cluster, the cluster should be unlocked to allow other users access to the cluster.
To lock a cluster, call the cluster-lock primitive. This primitive must be supplied with the following:
r the table id number, and
r the cluster id number.
cluster-lock locks a cluster, thus preventing other users from accessing it, and returns an error number indicating whether or not the primitive succeeded.
To unlock a cluster, call the cluster-unlock primitive. This primitive must be supplied with the following:
r the table id number, and
r the cluster id number.
cluster-unlock unlocks a cluster, allowing other users to access it, and returns an error number indicating whether or not the primitive succeeded.
The following sample method locks a cluster before replacing it, and then unlocks the cluster:
